home *** CD-ROM | disk | FTP | other *** search
/ World of Video / World of Video.iso / datafiles / gfx_formats / hdf / hdfs.ch4 < prev    next >
Text File  |  1995-02-13  |  7KB  |  183 lines
  1.  
  2.  
  3.  
  4. Chapter 4    HDF Conventions
  5.  
  6.  
  7.  
  8. Chapter Overview
  9. Byte Order
  10. Naming and Assigning Tags
  11. Using Reference Numbers to Organize Data 
  12. Objects
  13. Multiple References and File Compaction
  14.  
  15. Chapter Overview
  16.  
  17. The specification of HDF described in the previous chapter is not 
  18. sufficient to guarantee its success. With a general structure such 
  19. as HDF to work with, you may be tempted to create overly clever, 
  20. obscure, and complex files, defeating the purpose behind the design 
  21. of HDFÑto facilitate the interchange of data among differing 
  22. applications, programs, and computer systems. To guard against 
  23. these problems, a number of guidelines on the use of HDF are 
  24. provided:  some are implicit in the discussions in other sections of 
  25. this document and others are presented in the NCSA HDF manual. 
  26. Additional guidelines not covered elsewhere are introduced in this 
  27. section.
  28.  
  29.  
  30. Byte Order
  31.  
  32. The byte-ordering of data stored in memory and on files varies 
  33. from machine to machine.  It is important to address this 
  34. possibility in any software that processes data from files that might 
  35. have visited more than one machine.
  36.  
  37. In most cases, the existence of "byte-swapped" data can be detected 
  38. by examining the  Machine Type (MT) tag, which is described in 
  39. Appendix A.  Unfortunately, a program cannot look at the MT 
  40. until it has opened an HDF file and looked at the header, so it is 
  41. important that the byte order of the header be the same, no matter 
  42. what machine is used to create an HDF file.  Therefore, to 
  43. maintain machine portability when developing software for 
  44. machines that swap bytes, you should make sure that the characters 
  45. are read and written in the exact order specified (i.e., ^N^C^S^A).
  46.  
  47.  
  48. Naming and Assigning Tags
  49.  
  50. Tags that are to be made available to a general population of HDF 
  51. users should be assigned and controlled by NCSA. Tags of this type 
  52. are given numbers in the range 8,000 - 15,999. If you have an 
  53. application that fits this criterion, contact NCSA at the address 
  54. listed on the README page at the beginning of this manual and 
  55. specify the tags you would like. For each tag, your specifications 
  56. should include a suggested name, information about the type and 
  57. structure of the data that the tag will refer to, and information about 
  58. how the tag will be used. Your specifications should be similar to 
  59. those contained in Appendix A. NCSA will assign you a set of tags 
  60. for your application and include your tag descriptions in its 
  61. documentation.
  62.  
  63. Tags in the range 16,000 - 32,000 are user-definable. That is, you 
  64. can assign them for any private application. Of course, if you use 
  65. tags in this range you need to be aware that they may conflict with 
  66. other people's private tags.
  67.  
  68. Using Reference Numbers to Organize Data Objects
  69.  
  70. Reference numbers distinguish between one data object and others 
  71. with the same tag. It is often tempting to assign meaning to 
  72. reference numbers beyond this distinction. Such uses of reference 
  73. numbers are generally discouraged because most HDF software 
  74. assumes that reference numbers can be chosen or assigned in any 
  75. order, as long as all tag/ref combinations in a file remain unique.
  76.  
  77. On the other hand, in some situations reference number can be 
  78. used easily and effectively to add meaning to a fileÑfor instance, 
  79. to provide informal grouping and ordering of data objects. For 
  80. example, suppose you want to create a movie out of the images in an 
  81. HDF file. The images need to be ordered in some way and each 
  82. image needs to be associated with other data objects. In such cases, 
  83. you should refer to the following rules to assign reference 
  84. numbers, especially among sets of tags that are required to go 
  85. together.
  86.  
  87. 1.    Assign reference numbers in increasing order.
  88. 2.    When a companion object is required (for example, image 
  89. dimension is needed for images, use the object with the 
  90. current reference number. If none exists, use the object with 
  91. the next lowest reference number.
  92. 3.    When there are several combinations, cycle through 
  93. reference numbers for each tag type in ascending order in all 
  94. combinations that do not break the order.
  95.  
  96. For example, suppose the following data identifiers are in a file:  
  97. IP8[1], ID8[1], RI8[1], RI8[2], IP8[2], IP8[3], IP8[4], RI8[4], RI8[10], 
  98. DIL[1], DIL[10]. Objects in the file should be grouped in the order 
  99. shown in Table 4.1.
  100.  
  101.  
  102. Table 4.1    Sample Grouping of 
  103. Data Objects in an 
  104. HDF File
  105. IP8    ID8    RI8    DIL
  106. 1    1    1    1        palette[1], dimensions[1], image[1], label[1]
  107. 2    1    2    1        change to palette[2] and image[2]
  108. 3    1    2    1        change to palette[3]
  109. 4    1    4    1        change to palette[4] and image[4]
  110. 4    1    10    10        change to image[10] and label[10]
  111.  
  112.  
  113. Of course, these conventions only work if all of the programs that 
  114. touch a file do so without altering the reference numbering 
  115. scheme. If this cannot be guaranteed, you have a second 
  116. solutionÑto impose order on the file by means of a sorted, keyed 
  117. index. This is a good solution because it can provide random 
  118. access as well as ordered access to data; however, it adds a level of 
  119. complexity to what might otherwise be a simple sequential file 
  120. organization.
  121.  
  122. Multiple References and File Compaction
  123.  
  124. Multiple references to a single data element are quite common.  
  125. The general purpose routine DFdup (see Chapter 2) generates a new 
  126. reference to data that is already pointed to by another DD.  If DFdup 
  127. is used several times, there could be several DDs that point to the 
  128. same data element.  It is important to note that when such a 
  129. multiply referenced data element is moved, the various DDs that 
  130. pointed to the data element before it was moved are not 
  131. automatically adjusted to point to the data element in its new 
  132. location.
  133.  
  134. For example, when DFaccess is called for write access, the 
  135. referenced data is copied to the end of the HDF file to allow the user 
  136. to append to that element. The original data is not moved, only 
  137. copied. If there are multiple references to that data, then the old 
  138. references still point to the old data.
  139.  
  140. Consequently, compaction of a file should be done in the following 
  141. manner. Proceed through the data descriptors in order. For each 
  142. descriptor, determine whether the data has already been copied; if 
  143. not, copy the data into a new file and update its descriptor. If the 
  144. data has already been copied, as in the case of a multiple reference, 
  145. then the descriptor should be placed in the new file as a multiple 
  146. reference. Any data that no longer has a DD reference should not 
  147. be copied to the new file.
  148.  
  149. After updating elements, you may need to call DFdescriptors 
  150. again to make sure that your copy of the descriptors is up-to-date.
  151.  
  152. Of course, for most programs you will be writing, you only need to 
  153. create a completely new file, add elements to an existing file, or 
  154. read a pre-existing file. For all of these operations, consistency is 
  155. completely handled by the lower level HDF interface, even in the 
  156. case of multiple references to the same data.
  157.  
  158. 4.1    NCSA HDF Specifications
  159.  
  160. HDF Conventions    4.1
  161.  
  162. National Center for Supercomputing Applications
  163.  
  164. March 1989
  165.  
  166.                                                                 
  167.  
  168.  
  169.  
  170. 4.1    NCSA HDF Specifications
  171.  
  172. HDF Conventions    4.1
  173.  
  174. National Center for Supercomputing Applications
  175.  
  176. March 1989
  177.  
  178.                                                                 
  179.  
  180.  
  181.  
  182.  
  183.